feat(cli): add env file support by niyue · Pull Request #1006 · boxlite-ai/boxlite

niyue · 2026-07-17T15:51:31Z

Summary

Adds repeatable --env-file support to boxlite run, create, and exec, making it easier to configure guest environments without specifying every variable individually.
This PR closes #1005

Changes

Add shared environment handling for run, create, and exec.
Parse environment files using dotenvy, supporting standard dotenv syntax such as quotes, comments, export, escapes, and variable substitution.
Apply files in command-line order, with later files overriding earlier files and explicit -e values taking highest precedence.
Preserve existing -e KEY=value and host lookup behavior for bare -e KEY.
Add unit and integration coverage for parsing, precedence, missing or invalid files, and all three commands.
Document the new option and its precedence rules.

How to verify

make test:integration:cli FILTER=environment::tests
make test:integration:cli FILTER=env_file

Summary by CodeRabbit

New Features
- Added repeatable --env-file FILE support to boxlite run, create, and exec.
- Environment files are merged in order; later definitions override earlier ones, and explicit -e/--env takes precedence.
- -e KEY can be loaded from the host environment; if missing, earlier values are removed and a warning is shown.
Bug Fixes
- Clarified/support detached --tty behavior when standard input is not a TTY.
Documentation
- Updated CLI reference and shared flag groups with --env-file examples and dotenv precedence/override behavior.
Tests
- Added/updated integration tests covering precedence, overrides, missing/invalid env-file behavior, and --tty + --detach scenarios.

boxlite-agent · 2026-07-17T15:51:34Z

📦 BoxLite review — couldn't complete

claude exited 1

stdout:
{"type":"result","subtype":"success","is_error":true,"api_error_status":403,"duration_ms":344,"duration_api_ms":0,"num_turns":1,"result":"Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access","stop_reason":"stop_sequence","session_id":"10e4a231-b047-4464-8b4a-1cab7d3d19d5","total_cost_usd":0,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"inference_geo":"","iterations":[],"speed":"standard"},"modelUsage":{},"permission_denials":[],"terminal_reason":"api_error","fast_mode_state":"off","uuid":"5ea2e9f7-e708-4649-8407-432640c26297"}

stderr:
<empty>

_{powered by BoxLite}

cla-assistant · 2026-07-17T15:51:48Z

All committers have signed the CLA.

coderabbitai · 2026-07-17T15:52:10Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 504e2ebb-83fc-4548-b0f4-d6647d3d3d10

📥 Commits

Reviewing files that changed from the base of the PR and between 633c5be and 906421b.

📒 Files selected for processing (1)

src/cli/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

src/cli/README.md

📝 Walkthrough

Walkthrough

boxlite run, create, and exec now support repeatable dotenv files. Environment precedence, host lookup, command propagation, TTY behavior, tests, and CLI documentation were updated.

Changes

CLI environment file support

Layer / File(s)	Summary
Environment resolution and process flags `src/cli/src/environment.rs`, `src/cli/src/cli.rs`, `src/cli/src/main.rs`, `src/cli/Cargo.toml`	Adds repeatable dotenv loading, precedence handling, host lookup for bare keys, and resolved environment propagation through `ProcessFlags`.
Command environment propagation `src/cli/src/commands/create.rs`, `src/cli/src/commands/run.rs`, `src/cli/src/commands/exec.rs`	Passes resolved environment values into box creation and command configuration for `run`, `create`, and `exec`.
Coverage and CLI documentation `src/cli/tests/*`, `src/cli/README.md`, `docs/reference/cli/README.md`	Adds resolution, precedence, command integration, and TTY behavior tests, and documents `--env-file` and dotenv behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant EnvironmentFlags
  participant BoxRunner
  participant BoxExecutor
  participant BoxCommand
  CLI->>EnvironmentFlags: Resolve env files and explicit values
  EnvironmentFlags-->>CLI: Return environment pairs
  CLI->>BoxRunner: Run with environment pairs
  BoxRunner->>BoxCommand: Configure command environment
  CLI->>BoxExecutor: Execute with environment pairs
  BoxExecutor->>BoxCommand: Configure command environment

Possibly related PRs

boxlite-ai/boxlite#934: Modifies shared CLI argument and execution wiring in run.rs and create.rs, which may overlap with the environment propagation changes.

Suggested reviewers: dorianzheng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding CLI env-file support.
Description check	✅ Passed	The description includes Summary, Changes, and How to verify, matching the template closely.
Linked Issues check	✅ Passed	The PR implements repeatable --env-file support for run, create, and exec with dotenv parsing, precedence, and host lookup behavior.
Out of Scope Changes check	✅ Passed	The docs, tests, and refactorings all support the env-file feature and do not appear unrelated to the issue.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/cli/src/commands/create.rs`:
- Line 65: Update to_box_options to resolve self.environment at the beginning
and retain the resulting values locally, before invoking VolumeFlags::apply_to
or creating anonymous volumes. Apply the resolved environment to options.env
after the other option transformations, preserving existing error propagation
for missing or malformed environment files.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b317361e-0b94-4ae0-9b60-c7a7b9d4299b

📥 Commits

Reviewing files that changed from the base of the PR and between 2411669 and d3da034.

⛔ Files ignored due to path filters (1)

Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (13)

docs/reference/cli/README.md
src/cli/Cargo.toml
src/cli/README.md
src/cli/src/cli.rs
src/cli/src/commands/create.rs
src/cli/src/commands/exec.rs
src/cli/src/commands/run.rs
src/cli/src/environment.rs
src/cli/src/main.rs
src/cli/tests/common/mod.rs
src/cli/tests/create.rs
src/cli/tests/exec.rs
src/cli/tests/run.rs

DorianZheng

notes from a pass over the env-file feature; parser behavior checked against dotenvy 0.15.7 source. the important ones: parse errors echo secret values, ${...} substitution has two surprises (host env wins over the file's own lines; files can't see earlier files), and run -u quietly becomes active.

DorianZheng · 2026-07-22T12:02:07Z

@niyue Please fix the conflicts

coderabbitai

🧹 Nitpick comments (1)

src/cli/README.md (1)
403-420: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Make the environment behavior scope explicit.

This section appears under boxlite exec, but the documented rules also apply to run and create. Move it to a shared environment section or add an explicit heading such as “Environment behavior for run, create, and exec” so users of the other commands do not miss the precedence and substitution rules.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/README.md` around lines 403 - 420, Make the environment behavior
documentation explicitly apply to run, create, and exec rather than only the
surrounding exec section. Update the heading or relocate the section to shared
documentation while preserving all existing precedence, substitution, bare-key,
and secret-injection rules.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/cli/README.md`:
- Around line 403-420: Make the environment behavior documentation explicitly
apply to run, create, and exec rather than only the surrounding exec section.
Update the heading or relocate the section to shared documentation while
preserving all existing precedence, substitution, bare-key, and secret-injection
rules.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3300d7e8-0f8c-4895-9a8f-96437c377ae5

📥 Commits

Reviewing files that changed from the base of the PR and between 9554e64 and 633c5be.

⛔ Files ignored due to path filters (1)

Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (13)

docs/reference/cli/README.md
src/cli/Cargo.toml
src/cli/README.md
src/cli/src/cli.rs
src/cli/src/commands/create.rs
src/cli/src/commands/exec.rs
src/cli/src/commands/run.rs
src/cli/src/environment.rs
src/cli/src/main.rs
src/cli/tests/common/mod.rs
src/cli/tests/create.rs
src/cli/tests/exec.rs
src/cli/tests/run.rs

🚧 Files skipped from review as they are similar to previous changes (9)

src/cli/tests/exec.rs
src/cli/src/main.rs
src/cli/tests/common/mod.rs
src/cli/src/environment.rs
src/cli/src/commands/exec.rs
src/cli/tests/create.rs
src/cli/src/commands/create.rs
src/cli/src/commands/run.rs
src/cli/src/cli.rs

niyue requested a review from a team July 17, 2026 15:51

coderabbitai Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread src/cli/src/commands/create.rs Outdated

niyue force-pushed the feat/env-file branch from d3da034 to 924b167 Compare July 18, 2026 03:13

DorianZheng reviewed Jul 18, 2026

View reviewed changes

coderabbitai Bot mentioned this pull request Jul 21, 2026

fix(run): run COMMAND as the container init (docker semantics) #988

Merged

DorianZheng enabled auto-merge July 22, 2026 12:07

niyue added 10 commits July 22, 2026 22:48

feat(cli): add env file support

d827e7c

docs(cli): clarify env file substitution scope

4d56e2a

fix(cli): support BOM-prefixed env files

36a2f0e

fix(cli): redact env file parse errors

442316f

refactor(cli): simplify env file errors

e841401

fix(cli): preserve env flag compatibility

c9f7484

fix(cli): unset missing host env overrides

8748492

test(cli): cover env precedence edge cases

31c2b28

refactor(cli): centralize box process options

c797156

docs(cli): clarify environment behavior

633c5be

auto-merge was automatically disabled July 22, 2026 15:02
Head branch was pushed to by a user without write access

niyue force-pushed the feat/env-file branch from 9554e64 to 633c5be Compare July 22, 2026 15:02

coderabbitai Bot reviewed Jul 22, 2026

View reviewed changes

docs(cli): clarify environment behavior scope

906421b

Uh oh!

Conversation

niyue commented Jul 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

How to verify

Summary by CodeRabbit

Uh oh!

boxlite-agent Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 BoxLite review — couldn't complete

Uh oh!

cla-assistant Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DorianZheng left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DorianZheng commented Jul 22, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

niyue commented Jul 17, 2026 •

edited by coderabbitai Bot

Loading

boxlite-agent Bot commented Jul 17, 2026 •

edited

Loading

cla-assistant Bot commented Jul 17, 2026 •

edited

Loading

coderabbitai Bot commented Jul 17, 2026 •

edited

Loading